Skip to content

[WIP] src: do not enable wasm trap handler if there's not enough vmem#62132

Draft
joyeecheung wants to merge 2 commits intonodejs:mainfrom
joyeecheung:wasm-handler-2
Draft

[WIP] src: do not enable wasm trap handler if there's not enough vmem#62132
joyeecheung wants to merge 2 commits intonodejs:mainfrom
joyeecheung:wasm-handler-2

Conversation

@joyeecheung
Copy link
Member

@joyeecheung joyeecheung commented Mar 6, 2026 •
edited
Loading

The first commit is a backport of https://chromium-review.googlesource.com/c/v8/v8/+/7638233

This complements --disable-wasm-trap-handler and allows users to keep wasm functional in an environment with virtual memory restrictions (e.g. in the case of running VS code server for remote access, the user does not necessary always have the permission to configure the NODE_OPTIONS to configure --disable-wasm-trap-handler, and they don't necessarily even know this has anything to do with WASM on Node.js since they shouldn't be aware of what VS code server is implemented with).

Supersedes #60788 - this keeps the estimation logic in Node.js instead, and also keeps it in POSIX because on other systems the issue that this is solving is not practical (e.g. on Windows, one cannot bound the virtual memory available without bounding the physical memory, and it does not make a difference whether trap based bound checks are enabled or not when physical memory limit is reached)

  1. When the amount of virtual memory available does not allow more than 1 wasm cage at startup, Node.js automatically disables trap-based bound checks for wasm - in this case, no wasm can run at all if we keep the trap-based bound checks, so there's no point enabling the optimization. This should remove a good enough of reproductions of Out of memory: Cannot allocate Wasm memory for new instance (after update from 1.100.3 to 1.101) microsoft/vscode#251777
  2. When the amount of virtual memory allows more than 1 cage, but still less than the usual 128TB on 64-bit systems, the optimization is still optimistically enabled. In this case some initial wasm cage may be allocated but may fail later when there's not enough virtual memory left. This maintains the current behavior when we unconditionally enable the optimzation.
  3. --disable-wasm-trap-handler is kept as an escape hatch for 2.

We can tweak the threshold of estimation of needed wasm cages in 1 in Node.js to reduce the possibility of 2, this PR currently sets the threshold to 1.

Refs: microsoft/vscode#251777
Refs: https://chromium-review.googlesource.com/c/v8/v8/+/7638233

@nodejs-github-bot
Copy link
Collaborator

nodejs-github-bot commented Mar 6, 2026

Review requested:

  • @nodejs/gyp
  • @nodejs/security-wg
  • @nodejs/startup
  • @nodejs/v8-update

@nodejs-github-bot nodejs-github-bot added lib / src Issues and PRs related to general changes in the lib or src directory. needs-ci PRs that need a full CI run. labels Mar 6, 2026
@joyeecheung joyeecheung marked this pull request as draft March 6, 2026 14:51
@joyeecheung joyeecheung mentioned this pull request Mar 6, 2026
Closed
@codecov
Copy link

codecov bot commented Mar 6, 2026 •
edited
Loading

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 89.65%. Comparing base (b864049) to head (0c431d9).
⚠️ Report is 179 commits behind head on main.

Additional details and impacted files 
@@            Coverage Diff             @@
##             main   #62132      +/-   ##
==========================================
- Coverage   89.74%   89.65%   -0.10%     
==========================================
  Files         675      676       +1     
  Lines      204601   206424    +1823     
  Branches    39325    39537     +212     
==========================================
+ Hits       183616   185065    +1449     
- Misses      13273    13489     +216     
- Partials     7712     7870     +158
Files with missing lines Coverage Δ
src/debug_utils.h 80.00% <ø> (+1.42%) ⬆️
src/node.cc 76.75% <100.00%> (+0.46%) ⬆️

... and 197 files with indirect coverage changes

🚀 New features to boost your workflow:
  • ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.
  • 📦 JS Bundle Analysis: Save yourself from yourself by tracking and limiting bundle sizes in JS merges.

hubot pushed a commit to v8/v8 that referenced this pull request Mar 10, 2026
@joyeecheung
[api] Add V8::GetWasmMemoryReservationSizeInBytes()
bef0d9c 
When the system does not have enough virtual memory for the wasm
cage, installing the trap handler would cause any code allocating
wasm memory to throw. Therefore it's useful for the embedder to
know when the system doesn't have enough virtual address space
to allocate enough wasm cages and in that case, skip the
trap handler installation so that wasm code can at least work
(even not at the maximal performance).

Node.js previously has a command line option
--disable-wasm-trap-handler to fully disable trap-based bound checks,
this new API would allow it to adapt automatically while keeping the
optimization in the happy path, since it's not always possible for
end users to opt-into disabling trap-based bound checks (for example,
when a VS Code Server is loaded in a remote server for debugging).

Refs: nodejs/node#62132
Refs: microsoft/vscode#251777
Change-Id: I345c076af2b2b47700e5716b49c3133fdf8a0981
Reviewed-on: https://chromium-review.googlesource.com/c/v8/v8/+/7638233
Reviewed-by: Jakob Kummerow <jkummerow@chromium.org>
Reviewed-by: Michael Lippautz <mlippautz@chromium.org>
Commit-Queue: Joyee Cheung <joyee@igalia.com>
Reviewed-by: Clemens Backes <clemensb@chromium.org>
Cr-Commit-Position: refs/heads/main@{#105702}
@joyeecheung
deps: V8: backport bef0d9c1bc90
2be6a64 
Original commit message:

    [api] Add V8::GetWasmMemoryReservationSizeInBytes()

    When the system does not have enough virtual memory for the wasm
    cage, installing the trap handler would cause any code allocating
    wasm memory to throw. Therefore it's useful for the embedder to
    know when the system doesn't have enough virtual address space
    to allocate enough wasm cages and in that case, skip the
    trap handler installation so that wasm code can at least work
    (even not at the maximal performance).

    Node.js previously has a command line option
    --disable-wasm-trap-handler to fully disable trap-based bound checks,
    this new API would allow it to adapt automatically while keeping the
    optimization in the happy path, since it's not always possible for
    end users to opt-into disabling trap-based bound checks (for example,
    when a VS Code Server is loaded in a remote server for debugging).

    Refs: nodejs#62132
    Refs: microsoft/vscode#251777
    Change-Id: I345c076af2b2b47700e5716b49c3133fdf8a0981
    Reviewed-on: https://chromium-review.googlesource.com/c/v8/v8/+/7638233
    Reviewed-by: Jakob Kummerow <jkummerow@chromium.org>
    Reviewed-by: Michael Lippautz <mlippautz@chromium.org>
    Commit-Queue: Joyee Cheung <joyee@igalia.com>
    Reviewed-by: Clemens Backes <clemensb@chromium.org>
    Cr-Commit-Position: refs/heads/main@{#105702}

Refs: v8/v8@bef0d9c
Co-authored-by: Joyee Cheung <joyeec9h3@gmail.com>
@nodejs-github-bot

This comment was marked as outdated.

Sign in to view
@nodejs-github-bot
Copy link
Collaborator

nodejs-github-bot commented Mar 11, 2026

CI: https://ci.nodejs.org/job/node-test-pull-request/71683/

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Reviewers

No reviews

Assignees

No one assigned

Labels

lib / src Issues and PRs related to general changes in the lib or src directory. needs-ci PRs that need a full CI run.

Projects

None yet

Milestone

No milestone

Development

Successfully merging this pull request may close these issues.

2 participants

@joyeecheung @nodejs-github-bot